home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 676-700 / 680 / sattrack / ifflib20.lzh / IFFLib.doc < prev    next >
Text File  |  1990-10-09  |  16KB  |  542 lines
  1.  
  2.                  THE UNIVERSAL IFF LIBRARY FOR THE AMIGA
  3.  
  4.                         VERSION 19.1    09-OCT-90
  5.  
  6.  
  7.                 BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND
  8.  (UUCP: cbmvax.commodore.com!cbmehq!cbmswi!zethos!mighty!chris, BIX: chw)
  9.  
  10.  
  11. THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED
  12. AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES.  IT MAY BE DISTRIBUTED
  13. WITH OR WITHOUT THIS DOCUMENTATION FILE.   IF YOU INCLUDE THE LIBRARY WITH
  14. A COMMERCIAL PRODUCT, FEEL FREE TO SEND ME A FREE COPY OF THE PRODUCT.
  15.  
  16. TO MAINTAIN COMPATIBILITY, YOU SHOULD NOT MAKE ANY CHANGES TO THE LIBRARY.
  17. UPDATES WILL BE RELEASED BY THE AUTHOR.
  18.  
  19.  
  20.  
  21. WHAT IFF FILES CAN BE HANDLED?
  22. ------------------------------
  23.  
  24. I wrote this library to provide an easy way for reading and writing simple
  25. IFF files, such as pictures, animations, sound samples etc.
  26. In order to keep things easy, the IFF parser is NOT recursive. This means
  27. that it cannot handle files which contain recursive FORM or CAT definitions
  28. (e.g. a FORM containing another FORM).
  29. This restriction is not as important as you might think, since over 97%
  30. of all currently existing IFF files are not recursive. (Aren't statistics
  31. nice? ;-)
  32. If you really need a recursive IFF parser, you should use the original
  33. Electronic Arts code, or the WB 2.0 iffparse.library.
  34. Note that the iff.library can deal with ANIM files, although they contain
  35. nested FORMs. This is done with a little trick, see 'AnimExample.c' for
  36. details.
  37.  
  38.  
  39.  
  40. WHAT WILL BE CHANGED IN THE FUTURE
  41. ----------------------------------
  42.  
  43. The SaveBitMap() and SaveClip() functions currently are the only way to
  44. generate IFF files with this library. This is very un-flexible, since
  45. there is no way to add specific chunks to a file. So, I will add some
  46. general-purpose functions which allow you to easily write any IFF files
  47. of any type. Also, there will be a new method for specifying view modes,
  48. because there are lots of new modes in Kickstart 2.0.
  49. The new version (V20) should be ready in a few weeks.
  50.  
  51.  
  52.  
  53. LIBRARY FUNCTION OVERVIEW
  54. -------------------------
  55.  
  56. Name        Offset    Description
  57.  
  58. OpenIFF        -30    Allocate memory for an IFF-file and load it
  59. CloseIFF    -36    Finish access to an IFF-file and deallocate memory
  60. FindChunk    -42    Find a specific chunk in an IFF file
  61. GetBMHD        -48    Find the BitMapHeader of an ILBM file
  62. GetColorTab     -54    Find CMAP chunk, convert it to an Amiga ColorTable
  63. DecodePic    -60    Decode the BODY of an ILBM file into a BitMap
  64. SaveBitMap    -66    Save the contents of a BitMap as an IFF-file
  65. SaveClip    -72    Save a part of a BitMap as an IFF-file
  66. IFFError    -78    Get detailed error descrpition if a routine fails
  67. GetViewModes     -84    Get the Amiga-specific ViewModes
  68. NewOpenIFF    -90    Allocate specific memory for an IFF-file and load it
  69. ModifyFrame    -96    Modify an anim frame using a DLTA chunk
  70. (to be continued)
  71.  
  72.  
  73.  
  74. DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS
  75. ---------------------------------------------
  76.  
  77. (This documentation was translated from German to English in half an hour,
  78. so please be tolerant!)
  79.  
  80. iff.library/NewOpenIFF                                 iff.library/NewOpenIFF
  81.  
  82.    NAME
  83.     NewOpenIFF -- allocate memory for an IFF-file and read it
  84.  
  85.    SYNOPSIS
  86.     ifffile = NewOpenIFF(filename,memattr)
  87.      D0                   A0       D0
  88.  
  89.    LIBRARY OFFSET
  90.         -90
  91.  
  92.    FUNCTION
  93.     This function opens a file on a disk and looks whether it's an IFF
  94.     file or not. If it is an IFF file, memory is allocated and the file
  95.     is read into memory. The 'memattr' argument is taken to define the
  96.     memory type. Normally memattr is set to 0 or MEMF_PUBLIC.
  97.     If an error occurs, 0 is returned, and you can call IFFError() to
  98.     get the error number.
  99.  
  100.    INPUTS
  101.     filename - Pointer to a null-terminated string
  102.     memattr  - Memory requirements as used for Exec's AllocMem(),
  103.                such as MEMF_CHIP, MEMF_PUBLIC ...
  104.                (MEMF_CLEAR is not necessary)
  105.  
  106.    RESULT
  107.     ifffile - 'FileHandle', points to the beginning of the IFF file
  108.     ("FORM...."), Zero if unsuccessful. Call IFFError() to get the
  109.     reason of the failure.
  110.  
  111.    SEE ALSO
  112.     OpenIFF, CloseIFF, IFFError
  113.  
  114.    BUGS
  115.     None known
  116.  
  117.  
  118. iff.library/OpenIFF                                       iff.library/OpenIFF
  119.  
  120.    NAME
  121.     OpenIFF -- allocate memory for an IFF-file and read it
  122.  
  123.    SYNOPSIS
  124.     ifffile = OpenIFF(filename)
  125.      D0                A0
  126.  
  127.    LIBRARY OFFSET
  128.         -90
  129.  
  130.    FUNCTION
  131.     This function does the same as the NewOpenIFF() routine above,
  132.     except that you cannot specify the type of memory which is
  133.     allocated for the file. Normally the type is 0 which means 'any
  134.     memory', but if the IFF file type is '8SVX', the file is ALWAYS
  135.     loaded into CHIP memory. If you wish to override these defaults,
  136.     use NewOpenIFF() instead of OpenIFF().
  137.  
  138.    INPUTS
  139.     filename - Pointer to a null-terminated string
  140.  
  141.    RESULT
  142.     ifffile - 'FileHandle', points to the beginning of the IFF file
  143.     ("FORM...."), 0 if unsuccessful. Call IFFError() to get the
  144.     reason of the failure.
  145.  
  146.    SEE ALSO
  147.     NewOpenIFF, CloseIFF, IFFError
  148.  
  149.    BUGS
  150.     None
  151.  
  152.  
  153. iff.library/CloseIFF                                     iff.library/CloseIFF
  154.  
  155.    NAME
  156.     CloseIFF -- finish access to an IFF-file and deallocate memory
  157.  
  158.    SYNOPSIS
  159.     CloseIFF(ifffile)
  160.               A1
  161.  
  162.    LIBRARY OFFSET
  163.         -36
  164.  
  165.    FUNCTION
  166.     Returns the memory previously allocated by OpenIFF().
  167.  
  168.    INPUTS
  169.     ifffile - IFF file pointer, from OpenIFF()
  170.  
  171.    RESULT
  172.     none
  173.  
  174.    SEE ALSO
  175.     OpenIFF
  176.  
  177.    BUGS
  178.     If A1 contains garbage, an 81000005 Guru will visit you...
  179.  
  180.  
  181. iff.library/FindChunk                                   iff.library/FindChunk
  182.  
  183.    NAME
  184.     FindChunk -- find an IFF-chunk
  185.  
  186.    SYNOPSIS
  187.     chunk = FindChunk(ifffile,chunkname)
  188.      D0               A1       D0
  189.  
  190.    LIBRARY OFFSET
  191.         -42
  192.  
  193.    FUNCTION
  194.     Find a specific chunk in an IFF file
  195.  
  196.    INPUTS
  197.     ifffile - pointer to a FORM, normally the result of OpenIFF()
  198.     chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
  199.                 if chunkname is 0, FindChunk() returns a pointer to the
  200.                 first byte after the end of the current FORM. This can
  201.                 be used byANIM readers for jumping from FORM to FORM.
  202.  
  203.    RESULT
  204.     Pointer to the beginning of the chunk (that means to the chunk
  205.     name itself, followed by the chunk size), zero if chunk not found
  206.  
  207.    SEE ALSO
  208.     GetBMHD, GetColorTab
  209.  
  210.    BUGS
  211.     none known
  212.  
  213.  
  214. iff.library/GetBMHD                                       iff.library/GetBMHD
  215.  
  216.    NAME
  217.     GetBMHD -- find a BitMapHeader of an IFF-file
  218.  
  219.    SYNOPSIS
  220.     header = GetBMHD(ifffile)
  221.      D0              A1
  222.  
  223.    LIBRARY OFFSET
  224.         -48
  225.  
  226.    FUNCTION
  227.     Returns a pointer to a 'BitMapHeader' structure as defined in
  228.     iff.h and iff.i
  229.  
  230.    INPUTS
  231.     ifffile - IFF file pointer, returned by OpenIFF()
  232.  
  233.    RESULT
  234.     Pointer to the BitMapHeader, or 0 if no BMHD chunk found
  235.  
  236.    SEE ALSO
  237.     FindChunk, GetColorTab
  238.  
  239.    BUGS
  240.     none
  241.  
  242.  
  243. iff.library/GetColorTab                               iff.library/GetColorTab
  244.  
  245.    NAME
  246.     GetColorTab -- find a CMAP chunk and convert it to a ColorTable
  247.  
  248.    SYNOPSIS
  249.     count = GetColorTab(ifffile,colortable)
  250.      D0                  A1      A0
  251.  
  252.    LIBRARY OFFSET
  253.         -54
  254.  
  255.    FUNCTION
  256.     Searches the CMAP chunk of an IFF file and converts it, if it's
  257.     there, to an Amiga color table structure. This colortable can
  258.     directly be used as a parameter for the LoadRGB4() function.
  259.  
  260.    INPUTS
  261.     ifffile - IFF file pointer, returned by OpenIFF()
  262.     colortable - Pointer to a block of memory which must be large
  263.                  enough to hold the colortable (2 bytes per color)
  264.  
  265.    RESULT
  266.     Number of colors actually found, or zero if the file has no
  267.     CMAP chunk
  268.  
  269.    SEE ALSO
  270.     FindChunk, GetBMHD
  271.  
  272.    WARNING
  273.     the colortable must be WORD aligned
  274.  
  275.  
  276. iff.library/DecodePic                                   iff.library/DecodePic
  277.  
  278.    NAME
  279.     DecodePic -- decode the BODY of an ILBM file into a BitMap
  280.  
  281.    SYNOPSIS
  282.     success = DecodePic(ifffile,bitmap)
  283.      D0                 A1      A0
  284.  
  285.    LIBRARY OFFSET
  286.         -60
  287.  
  288.    FUNCTION
  289.     Decodes and decrunches a picture into the user supplied BitMap.
  290.     If the picture is larger than your BitMap's planes, it will be
  291.     truncated. If your BitMap is larger than the picture, the picture
  292.     will be drawn into the top left corner of your BitMap.
  293.     If the picture has less planes than the BitMap, the unused planes
  294.     are NOT touched by this routine, so you may wish to clear them
  295.     before calling DecodePic(). If the picture has more planes than
  296.     your BitMap, the surplus planes of the picture are ignored.
  297.  
  298.    INPUTS
  299.     ifffile - IFF file pointer, from OpenIFF()
  300.     bitmap  - Pointer to a properly initialized BitMap structure:
  301.           bm_Planes[] must point to valid BitPlanes,
  302.           bm_Depth contains the number of planes.
  303.           bm_Width and bm_Height must be set according to the
  304.           size of your bit planes.
  305.  
  306.    RESULT
  307.     Non-zero if  OK, 0 if error, Call IFFError() to know the reason
  308.     of the failure
  309.  
  310.    WARNING
  311.     This routine needs 620 bytes of stack space
  312.  
  313.  
  314. iff.library/SaveBitMap                                 iff.library/SaveBitMap
  315.  
  316.    NAME
  317.     SaveBitMap -- save the planes of a BitMap as an IFF-file
  318.  
  319.    SYNOPSIS
  320.     result = SaveBitMap(filename,bitmap,colortable,flags)
  321.      D0                  A0       A1     A2         D0
  322.  
  323.    LIBRARY OFFSET
  324.         -66
  325.  
  326.    FUNCTION
  327.     Save the planes of a BitMap as an IFF-file, optionally with a
  328.     colortable. The IFF file will contain the following chunks:
  329.  
  330.     FORM  -  The IFF header, with the type ILBM
  331.     BMHD  -  The BitMap Header structre
  332.     CMAP  -  The color map, this chunk is omitted if colortable is zero
  333.     CAMG  -  The Amiga ViewModes word, contains the special ViewModes
  334.              information (HAM, LACE, HIRES ...)
  335.     BODY  -  The (crunched or uncompressed) picture
  336.  
  337.    INPUTS
  338.     filename    - Name of the IFF file to create
  339.     bitmap      - Pointer to the BitMap holding your picture
  340.     colortable  - Pointer to an Amiga ColorTable structure or zero
  341.                   (if colortable = 0, no CMAP chunk will be generated).
  342.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  343.                          0 = Save the file uncompressed
  344.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  345.                          0 = This is a normal or Extra-Halfbrite picture
  346.  
  347.    RESULT
  348.     Non-zero if successful, 0 if error, Call IFFError() to know the
  349.     reason of the failure
  350.  
  351.    WARNING
  352.     This routine needs 620 bytes of stack space
  353.  
  354.    SEE ALSO
  355.     SaveClip
  356.  
  357.  
  358. iff.library/SaveClip                                     iff.library/SaveClip
  359.  
  360.    NAME
  361.     SaveClip -- save a part of a BitMap as an IFF-file
  362.  
  363.    SYNOPSIS
  364.     result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height)
  365.      D0                A0       A1     A2     D0    D1   D2   D3    D4
  366.  
  367.    LIBRARY OFFSET
  368.         -72
  369.  
  370.    FUNCTION
  371.     Save a part of a BitMap as an IFF file
  372.  
  373.    INPUTS
  374.     filename    - Name of the IFF file to create
  375.     bitmap      - Pointer to the BitMap holding your picture
  376.     colortable  - Pointer to an Amiga ColorTable structure or zero
  377.                   (if colortable = 0, no CMAP chunk will be generated).
  378.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  379.                          0 = Save the file uncompressed
  380.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  381.                          0 = This is a normal or Extra-Halfbrite picture
  382.     xoff        - X offset of the clip to be saved (bytes from the left)
  383.     yoff        - Y offset of the clip to be saved (lines from the top)
  384.     width       - width in bytes of the rectangle
  385.     height      - height in lines of the rectangle
  386.  
  387.    RESULT
  388.     Non-zero if successful, 0 if error, Call IFFError() to know the
  389.     reason of the failure
  390.  
  391.    WARNING
  392.     This routine needs 620 bytes of stack space
  393.  
  394.    SEE ALSO
  395.     SaveBitMap
  396.  
  397.    BUGS
  398.     The width of the rectangle will be rounded to WORD boundaries,
  399.     because DPAINT wants it!
  400.  
  401.  
  402. iff.library/IFFError                                     iff.library/IFFError
  403.  
  404.    NAME
  405.     IFFError -- Get detailed error descrpition
  406.  
  407.    SYNOPSIS
  408.     error = IFFError()
  409.     D0
  410.  
  411.    LIBRARY OFFSET
  412.         -78
  413.  
  414.    FUNCTION
  415.     If one of the above functions returns zero, you can call IFFError()
  416.     to know the reason for the failure. An error code is returned,
  417.     please refer to the files 'iff.h' or 'iff.i' for the complete
  418.     list of errors.
  419.  
  420.    INPUTS
  421.     none
  422.  
  423.    RESULT
  424.     Error-number generated by the latest function call, or zero if
  425.     no error
  426.  
  427.     Cuurently the following numbers are used:
  428.  
  429.     Nr.  Symbol             Function     Description
  430.  
  431.     16   IFF_CANTOPENFILE   OpenIFF()     File not found
  432.     17   IFF_READERROR      OpenIFF()     Read() returned an error
  433.     18   IFF_NOMEM          OpenIFF()     Not enough memory for the file
  434.     19   IFF_NOTIFF         OpenIFF()     File is not IFF
  435.     20   IFF_WRITEERROR    SaveBitMap()  Cannot write the file
  436.  
  437.     24   IFF_NOILBM         DecodePic()   IFF file is not an ILBM file
  438.     25   IFF_NOBMHD         DecodePic()   BMHD chunk not found
  439.     26   IFF_NOBODY         DecodePic()   BODY chunk not found
  440.     27   IFF_TOOMANYPLANES  DecodePic()   Picture has more planes than the
  441.                                           BitMap (OBSOLETE SINCE 18.7!)
  442.     28   IFF_UNKNOWNCOMPRESSION  "        Unknown compression type
  443.     29   IFF_NOANHD         ModifyFrame() ANHD chunk not found
  444.     30   IFF_NODLTA         ModifyFrame() DLTA chunk not found
  445.  
  446.     -1   IFF_BADTASK        A task which did not open the IFF library
  447.                             tried to call IFFError(). Since the IFF
  448.                             library is capable of multi-tasking, the
  449.                             error-values are stored for each task
  450.                             separately.
  451.  
  452.    SEE ALSO
  453.  
  454.    BUGS
  455.     If you don't close the IFF library at the end of your program
  456.     (using CloseLibrary()) the error node will not be freed. The
  457.     same task will then not be able to re-open the iff.library.
  458.     (This is not a bug, it's a feature ;-))
  459.  
  460.  
  461. iff.library/GetViewModes                             iff.library/GetViewModes
  462.  
  463.    NAME
  464.     GetViewModes -- Get Amiga-specific ViewModes
  465.  
  466.    SYNOPSIS
  467.     viewmodes = GetViewModes(ifffile)
  468.     D0                        A1
  469.  
  470.    LIBRARY OFFSET
  471.         -84
  472.  
  473.    FUNCTION
  474.     Searches the IFF file for a 'CAMG' chunk which holds the view modes
  475.     information. If there is no CAMG chunk, the view modes are calcu-
  476.     lated using the information in the BitMapHeader structure.
  477.     You can directly put the low WORD of the result of a GetViewModes()
  478.     call into the ns_ViewModes field of a NewScreen structure. All
  479.     forbidden bits are masked out, as suggested by CBM.
  480.  
  481.    INPUTS
  482.     ifffile - IFF file pointer, returned from OpenIFF()
  483.  
  484.    RESULT
  485.     viewmodes - LONG containing the view modes (HAM, LACE, HIRES ...)
  486.     Under Kickstart V1.3, only the lower WORD is used.
  487.  
  488.    SEE ALSO
  489.  
  490.    BUGS
  491.     If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit
  492.     will be set. This is not always correct since the picture could
  493.     be in the Extra Halfbrite mode. You can load such Halfbrite
  494.     pictures into DPaint III and save them again, DPaint will generate
  495.     the correct CAMG chunk.
  496.  
  497. iff.library/ModifyFrame                               iff.library/ModifyFrame
  498.  
  499.    NAME
  500.     ModifyFrame -- Modify an anim frame using a DLTA chunk
  501.  
  502.    SYNOPSIS
  503.     success = ModifyFrame(modifyform,bitmap)
  504.      D0                   A1         A0
  505.  
  506.    LIBRARY OFFSET
  507.         -96
  508.  
  509.    FUNCTION
  510.     Uses the DLTA chunk of the supplied FORM to modify the planes-data
  511.     of the bitmap. Usually, playback of ANIMs will require two buffers,
  512.     and double-buffering between them. So the data in the bitmap must
  513.     be two frames back, and the DLTA chunk is used to modify the hidden
  514.     frame to the next frame to be shown.
  515.  
  516.    INPUTS
  517.     modifyform - pointer to the FORM containing the actual DLTA chunk
  518.     bitmap  - Pointer to a properly initialized BitMap structure,
  519.           the planes must contain the image which was displayed
  520.           to frames back (using double-buffering)
  521.  
  522.    RESULT
  523.     Non-zero if  OK, 0 if error; call IFFError() to know the reason
  524.     of the failure
  525.  
  526.    RESTRICTIONS
  527.     Currently, only compression type 5 (Byte Vertical Delta Mode) is
  528.     implemented. If you have animations which use modes 1 to 4, try
  529.     loading them with DPaint III and saving them again.
  530.     Sculpt-Animate pictures do not work, because I have no documentation
  531.     about the compression scheme they use.
  532.     I will implement some more compression types upon request.
  533.  
  534.    WARNINGS
  535.     This routine needs at least 820 bytes of stack.
  536.     The size of the bitmap is not checked by this routine, the planes
  537.     must have at least the size described in the BMHD of the anim
  538.     file.
  539.  
  540.    BUGS
  541.  
  542.